<html><head><title>Specify a Smoothing Cubic Spline Fit in a GAMLSS Formula</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="Rchm.css">
</head>
<body>

<table width="100%"><tr><td>cs(gamlss)</td><td align="right">R Documentation</td></tr></table><object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
<param name="keyword" value="R:   cs">
<param name="keyword" value="R:   vc">
<param name="keyword" value="R:   scs">
<param name="keyword" value=" Specify a Smoothing Cubic Spline Fit in a GAMLSS Formula">
</object>


<h2>Specify a Smoothing Cubic Spline Fit in a GAMLSS Formula</h2>


<h3>Description</h3>

<p>
The functions <code>cs()</code> <code>scs()</code> and <code>vc</code> are using cubic smoothing splines. 
They take a vector and return it with several attributes. 
The vector is used in the construction of the model matrix.  The functions  do no smoothing, 
but assigns the attributes to the vector to aid gamlss in the smoothing.
The function doing the smoothing are <code><a href="gamlss.cs.html">gamlss.cs</a>()</code>, <code>gamlss.scs()</code> and <code>gamlss.vc()</code>.
The <code><a href="gamlss.cs.html">gamlss.cs</a>()</code>   is a modified version of the R function 
<code>smooth.spline()</code> which is used by the backfitting function <code><a href="additive.fit.html">additive.fit</a></code>.
The function  <code>gamlss.scs()</code>  just uses   <code>smooth.spline()</code>. It differs from the function <code>cs()</code> 
in that allows cross valdation of the smoothing parameters.   
The (experimental) function <code>vc</code> can be use to fit varying coefficient models, see Hastie and Tibshirani (1993).
</p>


<h3>Usage</h3>

<pre>
cs(x, df = 3, spar = NULL, c.spar = NULL)
vc(r, x, df = 3, spar = NULL, c.spar = NULL)
scs(x, df = NULL, spar = NULL, control.spar = NULL, all.knots = TRUE, nknots = NULL, penalty =1.4)
</pre>


<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>x</code></td>
<td>
the univariate predictor, (or expression, that evaluates to a numeric vector). 
For the function <code>vc</code> the x argument is the vector which has its (linear) coefficient change with <code>r</code></td></tr>
<tr valign="top"><td><code>df</code></td>
<td>
the desired equivalent number of degrees of freedom (trace of the smoother matrix minus two for the constant and linear fit).
The real smoothing parameter (spar below) is found such that df=tr(S)-2, 
where S is the implicit smoother matrix. Values for df should be greater than 0, with 0 implying a linear fit.</td></tr>
<tr valign="top"><td><code>spar</code></td>
<td>
smoothing parameter, typically (but not necessarily) in (0,1].   
The coefficient lambda of the integral of the squared second derivative in the fit (penalized log likelihood)
criterion is a monotone function of `spar', see the details in <code>smooth.spline</code>.</td></tr>
<tr valign="top"><td><code>c.spar</code></td>
<td>
This is an option to be used when the degrees of freedom of the fitted gamlss object are different from the ones given 
as input in the option <code>df</code>.  The default values used are the ones given  the  option <code>control.spar</code>   
in the R function <code>smooth.spine()</code> and they are <code>c.spar=c(-1.5, 2)</code>. 
For  very large data sets e.g. 10000 observations, the upper limit may have to increase for example to  <code>c.spar=c(-1.5, 2.5)</code>.
Use this option if you have received the warning 'The output df are different from the input, change the control.spar'.
<code>c.spar</code> can take both vectors or lists of length 2, for example <code>c.spar=c(-1.5, 2.5)</code>
or <code>c.spar=list(-1.5, 2.5)</code> would have the same effect.</td></tr>
<tr valign="top"><td><code>r</code></td>
<td>
for the function <code>vc</code>, <code>r</code> represent the vector of the explanatory variable which effects the coefficients of <code>x</code>
i.e. beta(r)*x.  Both the <code>x</code> and <code>r</code> vectors should be adjusted by subtracting the their mean</td></tr>
<tr valign="top"><td><code>control.spar</code></td>
<td>
see above <code>c.spar</code> or the equivalent argument in the function <code>smooth.spline</code>.</td></tr>
<tr valign="top"><td><code>all.knots</code></td>
<td>
if TRUE, all distinct points in x are used as knots. If FALSE (default), a subset of x is used, see the same argument for function 
<code>smooth.spline</code></td></tr>
<tr valign="top"><td><code>nknots</code></td>
<td>
integer giving the number of knots to use when all.knots=FALSE. Per default, this is less than n, the number of unique x values for n &gt; 49</td></tr>
<tr valign="top"><td><code>penalty</code></td>
<td>
the penalty applied to cross validation</td></tr>
</table>

<h3>Details</h3>

<p>
Note that <code>cs</code> itself does no smoothing; it simply sets things up for the function <code>gamlss()</code> which in turn uses the function 
<code>additive.fit()</code> for backfitting which in turn uses <code>gamlss.cs()</code>
</p>
<p>
Note that  <code>cs()</code> and  <code>s()</code> functions behave differently at their default values that is if df and lambda are not specified.
<code>cs(x)</code> by default will use 3 extra degrees of freedom for smoothing for <code>x</code>.
<code>ps(x)</code> by default will estimate lambda (and the degrees of freedom) automatically using generalised cross validation (GCV).
Note that if GCV is used the convergence of the gamlss model  can be  less stable
compared to a model where the degrees of freedom are fixed. This can be true especially for small data sets.
</p>


<h3>Value</h3>

<p>
the vector x is returned, endowed with a number of attributes. The vector itself is used in the construction of the model matrix, 
while the attributes are needed for the backfitting algorithms <code>additive.fit()</code>. 
Since smoothing splines includes linear fits, the linear part will be efficiently computed with the other parametric linear parts of the model.</p>

<h3>Warning</h3>

<p>
For a user who wishes to compare the <code>gamlss()</code> results with the equivalent <code>gam()</code> 
results in S-plus: make sure when using S-plus that the convergence criteria epsilon and bf.epsilon in <code>control.gam()</code> are decreased sufficiently
to ensure proper convergence in S-plus. 
Also note that the degrees of freedom are defined on top of the linear term in <code>gamlss</code>, but on top of the constant term in S-plus, 
(so use an extra degrees of freedom in S-plus in order to obtain comparable results to those in <code>galmss</code>).
</p>
<p>
Change the upper limit of spar if you received the warning 'The output df are different from the input, change the control.spar'.
</p>
<p>
For large data sets do not use expressions, e.g. <code>cs(x^0.5)</code> inside the <code>gamlss</code> function command but evaluate the expression, 
e.g. nx=<i>x^0.5</i>, first and then use <code>cs(nx)</code>.
</p>


<h3>Note</h3>

<p>
The degrees of freedom df are defined differently from that of the gam() function in S-plus. Here df are the additional degrees of freedom 
excluding the constant and the linear part of x. For example <code>df=4</code> in <code>gamlss()</code> is equivalent to <code>df=5</code> in <code>gam()</code> in S-plus
</p>


<h3>Author(s)</h3>

<p>
Mikis Stasinopoulos and Bob Rigby
</p>


<h3>References</h3>

<p>
Hastie, T. J. and Tibshirani, R. J. (1993), Varying coefficient models (with discussion),J. R. Statist. Soc. B., <B>55</B>,
757-796.
</p>
<p>
Rigby, R. A. and  Stasinopoulos D. M. (2005). Generalized additive models for location, scale and shape,(with discussion), 
<EM>Appl. Statist.</EM>, <B>54</B>, part 3, pp 507-554.
</p>
<p>
Stasinopoulos D. M., Rigby R.A. and Akantziliotou C. (2006) Instructions on how to use the GAMLSS package in R.
Accompanying documentation in the current GAMLSS  help files, (see also  <a href="http://www.gamlss.com/">http://www.gamlss.com/</a>).
</p>
<p>
Stasinopoulos D. M. Rigby R.A. (2007) Generalized additive models for location scale and shape (GAMLSS) in R.
<EM>Journal of Statistical Software</EM>, Vol. <B>23</B>, Issue 7, Dec 2007, <a href="http://www.jstatsoft.org/v23/i07">http://www.jstatsoft.org/v23/i07</a>.
</p>


<h3>See Also</h3>

<p>
<code><a href="gamlss.html">gamlss</a></code>, <code><a href="gamlss.cs.html">gamlss.cs</a></code>, <code><a href="lo.html">lo</a></code>
</p>


<h3>Examples</h3>

<pre>
# cubic splines example
data(aids)
# fitting a smoothing cubic spline with 7 degrees of freedom
# plus the a quarterly  effect  
aids1&lt;-gamlss(y~cs(x,df=7)+qrt,data=aids,family=PO) # 
aids2&lt;-gamlss(y~scs(x,df=5)+qrt,data=aids,family=PO) # 
aids3&lt;-gamlss(y~scs(x)+qrt,data=aids,family=PO) # using GCV 
with(aids, plot(x,y))
lines(aids$x,fitted(aids1), col="red")
lines(aids$x,fitted(aids3), col="green")
rm(aids1, aids2, aids3)
# varying-coefficient example
data(rent)
attach(rent)
# adjusting the variables
Flbar&lt;-Fl-mean(Fl)
Abar&lt;-A-mean(A)
# additive model
 m1&lt;-gamlss(R~cs(Flbar, df=3)+cs(Abar))
# varying-coefficient model
 m2&lt;-gamlss(R~cs(Flbar, df=3)+cs(Abar)+vc(r=Abar,x=Flbar))
AIC(m1,m2)
detach(rent)
</pre>



<hr><div align="center">[Package <em>gamlss</em> version 3.0-0 <a href="00Index.html">Index</a>]</div>

</body></html>
